home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Utilities / Programming / C Reference Card 2.3 / C Reference Card / C Reference Card.rsrc / TEXT_413_13.txt < prev    next >
Encoding:
Text File  |  1995-11-14  |  16.0 KB  |  647 lines
  1. ANSI LIBRARY : stdio, stdlib, string, math, ctype, time, stdarg, limits
  2. _________________________________________________________________________
  3.  
  4.  
  5. The following is a synopsis of functions available in the standard ANSI C library.  Other on-line reference tools (i.e., Symantec THINK Reference) provide a more detailed review of the ANSI C Library functions, but a quick review of these functions is provided in this section for your convenience.  
  6.  
  7. As a note, if you plan on programming for the MacOS, you'll find that you won't be using the ANSI C library as much as you might think.  This goes especially for input and output functions.  This means that you probably don't need to spend a lot of time learning the ins and outs of the ANSI C library - although you should at least be aware of the capabilities it provides.
  8.  
  9. Here's a list of the ANSI C library header files:
  10.  
  11.   <stdio.h>
  12.   <stdlib.h>
  13.   <string.h>
  14.   <math.h>
  15.   <ctype.h>
  16.   <time.h>
  17.   <stdarg.h>
  18.   <limits.h>
  19.   <float.h>
  20.   <assert.h>
  21.   <setjmp.h>
  22.   <signal.h>
  23.  
  24.  
  25.  
  26. STANDARD INPUT/OUTPUT <stdio.h>
  27. _________________________________________________________________________
  28.  
  29. Filenames are limited to FILENAME_MAX characters.  At most FOPEN_MAX files may be open at a given time.
  30.  
  31. CLEARERR
  32. void clearerr(FILE *stream)
  33.  
  34. FCLOSE
  35. int fclose(FILE *stream)
  36. Returns EOF if error occurs, zero otherwise.
  37.  
  38. FEOF
  39. int feof(FILE *stream)
  40. Returns non-zero if EOF is set.
  41.  
  42. FERROR
  43. int ferror(FILE *stream)
  44. Returns non-zero if error exists for 'stream'.
  45.  
  46. FFLUSH
  47. int fflush(FILE *stream)
  48. Returns EOF if error, zero otherwise.  fflush(NULL) flushes all output streams.
  49.  
  50. FGETC
  51. int fgetc(FILE *stream)
  52. Returns EOF if error.
  53.  
  54. FGETS
  55. char *fgets(char *s, int n, FILE *stream)
  56. Returns s, or NULL if error.
  57.  
  58. FGETPOS
  59. int fgetpos(FILE *stream, fpos_t *ptr)
  60. Records current position in 'stream' in '*ptr'.
  61.  
  62. FOPEN
  63. FILE *fopen(const char *filename, const char *mode)
  64. modes: "r"   read only
  65.        "w"   write; discard previous contents
  66.        "a"   append
  67.        "r+"  read and write
  68.        "rb"  read (binary)
  69.        "wb"  write (binary)
  70.        "ab"  append (binary)
  71.        "r+b" read and write (binary)
  72.  
  73. FPRINTF
  74. int fprintf(FILE *stream, const char *format, ...)
  75. Returns number of characters printed, or negative result if error.  Conversion specification begins with '%' and ends with conversion character.  In between, there may be (in order):
  76. flags:
  77.   '-' left justify
  78.   '+' print with sign
  79.   ' ' <space> prefix with space if no sign
  80.   '0' <zero> specifies padding with leading zeros
  81.   '#' alternate output form
  82. numbers:
  83.    n  first number specifies field width
  84.   '.' period used as separator
  85.    n  second number specifies precision (max characters)
  86.    m  modifier (h - short, l - long, L - long double)
  87. format characters:
  88.   d,i int; signed
  89.    o  int; unsigned octal (without leading zero)
  90.   x,X int; unsigned hexadecimal
  91.    u  int; unsigned
  92.    c  int; single character
  93.    s  char *; string
  94.    f  double;
  95.   e,E double; scientific notation
  96.   g,G double; %e or %f format, depending on value
  97.    p  void *; pointer
  98.    n  int *; number of characters written so far
  99.    %  no argument, print '%'
  100. example:
  101.   fprintf( myFilename, "The results are %d and %6.2f\n", myInt, myReal);
  102.  
  103. FPUTC
  104. int fputc(int c, FILE *stream)
  105. Returns c, or EOF if error.
  106.  
  107. FPUTS
  108. int fputs(const char *s, FILE *stream)
  109. Returns non-negative result, or EOF if error.
  110.  
  111. FREAD
  112. size_t fread(void *ptr, size_t size, size_t nobj, FILE *stream)
  113. Reads from 'stream' into 'ptr' at most 'nobj' objects of size 'size'.  Returns number of objects read.
  114.  
  115. FREOPEN
  116. FILE *freopen(const char *filename, const char *mode, FILE *stream)
  117. Returns NULL if error.
  118.  
  119. FSCANF
  120. int fscanf(FILE *stream, const char *format, ...)
  121. Reads from 'stream' and assigns values through subsequent arguments which must be pointers.  Returns EOF if end of file occurs before any conversion; otherwise it returns number of items assigned.  Format string should contain conversion specifications consisting of '%' followed by:
  122. flag:
  123.    *  suppression; ignore field
  124. number:
  125.    n  first number specifies maximum field width
  126. width character:
  127.    h  short
  128.    l  long
  129.    L  long double
  130. conversion characters:
  131.    d  int *
  132.    i  int *; may be octal (leading 0) or hexadecimal (leading 0x)
  133.    o  int *; octal integer
  134.    x  int *; hexadecimal integer
  135.    c  char *; characters
  136.    s  char *; string of non-white characters
  137.   e,f float *; could also use 'g'
  138.    p  void *; pointer
  139.    n  int *; writes into arg number of characters read.  Nothing read.
  140.  
  141. FSEEK
  142. int fseek(FILE *stream, long offset, int origin)
  143. Sets file position.  Values for origin can be:
  144.   SEEK_SET  beginning
  145.   SEEK_CUR  current position
  146.   SEEK_END  end of file
  147.  
  148. FSETPOS
  149. int fsetpos(FILE *stream, const fpos_t *ptr)
  150. Positions 'stream' at position recorded by fgetpos.  Returns non-zero if error.
  151.  
  152. FTELL
  153. long ftell(FILE *stream)
  154. Returns current position for 'stream', or -1L if error.
  155.  
  156. FWRITE
  157. size_t fwrite(const void *ptr, size_t size, size_t nobj, FILE *stream)
  158. Writes from 'ptr' to 'stream' 'nobj' objects of size 'size'.  Returns number of objects read.
  159.  
  160. GETC
  161. int getc(FILE *stream)
  162. Same as fgetc, except a macro.
  163.  
  164. GETCHAR
  165. int getchar(void)
  166. Equivalent to getc(stdin).
  167.  
  168. GETS
  169. char *gets(char *s)
  170. Returns s, or NULL if error.
  171.  
  172. PERROR
  173. void perror(const char *s)
  174. Prints error message 's'.
  175.  
  176. PRINTF
  177. int printf(const char *format, ...)
  178. Equivalent to fprintf(stdout, ...)
  179.  
  180. PUTC
  181. int putc(int c, FILE *stream)
  182. Same as fputc, except a macro.
  183.  
  184. PUTCHAR
  185. int putchar(int c)
  186. Equivalent to putc(c, stdout).
  187.  
  188. PUTS
  189. int puts(const char *s)
  190. Returns non-negative result, or EOF if error.
  191.  
  192. REMOVE
  193. int remove(cost char *filename)
  194. Returns non-zero if attempt to delete file fails.
  195.  
  196. RENAME
  197. int rename(const char *oldname, const char *newname)
  198. Returns non-zero if attempt to rename file fails.
  199.  
  200. REWIND
  201. void rewind(FILE *stream)
  202.  
  203. SCANF
  204. int scanf(const char *format, ...)
  205. Identical to fscanf(stdin, ...)
  206.  
  207. SPRINTF
  208. int sprintf(char *s, const char *format, ...)
  209. Same as printf except output written to string 's'.
  210.  
  211. SSCANF
  212. int sscanf(char *s, const char *format, ...)
  213. Equivalent to scanf(...) except input is taken from 's'.
  214.  
  215. SETBUF
  216. void setbuf(FILE *stream, char *buf)
  217. If 'buf' is NULL, buffering is turned off, otherwise equivalent to 'void setvbuf(stream, buf, _IOFBF, BUFSIZE)'.
  218.  
  219. SETVBUF
  220. int setvbuf(FILE *stream, char *buf, int mode, size_t size)
  221. Returns non-zero if error.  A value of NULL for 'buf' allocates buffer.
  222. modes: _IOFBF  full buffering
  223.        _IOLBF  line buffering
  224.        _IONBF  no buffering
  225.  
  226. TMPFILE
  227. FILE *tmpfile(void)
  228. Returns NULL if error.
  229.  
  230. TMPNAM
  231. char *tmpnam(char s[L_tmpnam])
  232. tmpnam(NULL) creates unique filename.  TMP_MAX different names guaranteed.
  233.  
  234. UNGETC
  235. int ungetc(int c, FILE *stream)
  236. pushes 'c' (converted to an unsigned char) back onto 'stream'.  Returns 'c' or EOF if error.
  237.  
  238. VPRINTF
  239. int vprintf(const char *format, va_list arg)
  240.  
  241. VFPRINTF
  242. int vfprintf(FILE *stream, const char *format, va_list arg)
  243.  
  244. VSPRINTF
  245. int vsprintf(char *s, const char *format, va_list arg)
  246.  
  247.  
  248.  
  249. STANDARD LIBRARY <stdlib.h>
  250. _________________________________________________________________________
  251.  
  252. ABORT
  253. void abort(void)
  254. Causes program to abnormally terminate.
  255.  
  256. ABS
  257. int abs(int n)
  258.  
  259. ATEXIT
  260. int atexit(void (*fcn)(void))
  261. Registers function to be called when program terminates.  Returns non-zero if error.
  262.  
  263. ATOF
  264. double atof(const char *s)
  265.  
  266. ATOI
  267. int atoi(const char *s)
  268.  
  269. ATOL
  270. long atol(const char *s)
  271.  
  272. BSEARCH
  273. void *bsearch(const void *key, const void *base, size_t n, size_t size, int (*cmp)(const void *keyval, const void *datum))
  274.  
  275. CALLOC
  276. void *calloc(size_t nobj, size_t size)
  277.  
  278. DIV
  279. div_t div(int num, int denom)
  280.  
  281. EXIT
  282. void exit(int status)
  283. Causes normal program termination.
  284.  
  285. FREE
  286. void free(void *p)
  287. Deallocates spaced pointed to by 'p'.  Returns NULL is error.
  288.  
  289. GETENV
  290. char *getenv(const char *name)
  291.  
  292. LABS
  293. long labs(long n)
  294.  
  295. LDIV
  296. ldiv_t ldiv(long num, long denom)
  297.  
  298. MALLOC
  299. void *malloc(size_t size)
  300. Returns pointer for object of size 'size', or NULL if request for memory denied.
  301.  
  302. QSORT
  303. void qsort(void *base, size_t n, size_t size, int (*cmp)(const void *, const void *))
  304.  
  305. RAND
  306. int rand(void)
  307. Returns pseudo-random integer between 0 and RAND_MAX.
  308.  
  309. REALLOC
  310. void *realloc(void *p, size_t size)
  311.  
  312. STRTOD
  313. double strtod(const char *s, char **endp)
  314.  
  315. STRTOL
  316. long strtol(const char *s, char **endp, int base)
  317.  
  318. STRTOUL
  319. unsigned long strtoul(const char *s, char **endp, int base)
  320.  
  321. SRAND
  322. void srand(unsigned int seed)
  323.  
  324. SYSTEM
  325. int system(const char *s)
  326.  
  327.  
  328.  
  329. STRING FUNCTIONS <string.h>
  330. _________________________________________________________________________
  331.  
  332. MEMCHR
  333. void *memchr(const char *cs, int c, size_t n)
  334. Returns first occurrence of character 'c' in 'cs' or NULL.
  335.  
  336. MEMCMP
  337. int memcmp(const char *cs, const char *ct, size_t n)
  338. Compares 'n' characters of 'cs' with 'ct'.
  339.  
  340. MEMCPY
  341. void *memcpy(char *s, const char *ct, size_t n)
  342. Copy 'n' characters from 'ct' to 's', returns 's'.
  343.  
  344. MEMMOVE
  345. void *memmove(char *s, const char *ct, size_t n)
  346. Same as 'memcpy'.  Works if objects overlap.
  347.  
  348. MEMSET
  349. void *memset(char *s, int c, size_t n)
  350. Put character 'c' into first 'n' characters of 's', returns 's'.
  351.  
  352. STRCAT
  353. char *(char *char *s, const char *ct)
  354. Concatenates 'ct' to 's', returns 's'.
  355.  
  356. STRCHR
  357. char *strchr(const char *cs, int c)
  358. Returns pointer to first occurrence of 'c' in 'cs' or NULL.
  359.  
  360. STRCMP
  361. int strcmp(const char *cs, const char *ct)
  362. Returns zero is cs == ct.
  363.  
  364. STRCPY
  365. char *strcpy(char *s, const char *ct)
  366. Copies 'ct' to 's', including '\0', returns 's'.
  367.  
  368. STRCSPN
  369. size_t strcspn(const char *cs, const char *ct)
  370.  
  371. STRERROR
  372. char *strerror(n)
  373. Returns pointer to string defining error 'n'.
  374.  
  375. STRLEN
  376. size_t strlen(const char *cs)
  377. Returns length of 'cs'.
  378.  
  379. STRNCAT
  380. char *strncat(char *s, const char *ct, size_t n)
  381.  
  382. STRNCMP
  383. int strncmp(const char *cs, const char *ct, size_t n)
  384. Returns zero if 'n' characters of both strings are equal.
  385.  
  386. STRNCPY
  387. char *strncpy(char *s, const char *ct, size_t n)
  388.  
  389. STRPBRK
  390. char *strpbrk(const char *cs, const char *ct)
  391. Return pointer to first occurrence of any character in 'ct' or NULL.
  392.  
  393. STRRCHR
  394. char *strrchr(const char *cs, int c)
  395. Returns pointer to last occurrence of 'c' in 'cs' or NULL.
  396.  
  397. STRSPN
  398. size_t strspn(const char *cs, const char *ct)
  399.  
  400. STRSTR
  401. char *strstr(const char *cs, const char *ct)
  402. Returns pointer to first occurrence of string 'ct' in 'cs' or NULL.
  403.  
  404. STRTOK
  405. char *strtok(char *s, const char *ct)
  406. Searches 's' for tokens delimited by characters from 'ct'.  Returns NULL when no further tokens found.
  407.  
  408.  
  409.  
  410. MATH FUNCTIONS <math.h>
  411. _________________________________________________________________________
  412.  
  413. In the following list, 'x' and 'y' are type 'double', n is type 'int'.  All angles for trigonometric functions are in radians.
  414.  
  415.   sin(x)
  416.   cos(x)
  417.   tan(x)
  418.   asin(x)
  419.   acos(x)
  420.   atan(x)
  421.   atan2(y,x)
  422.   sinh(x)
  423.   cosh(x)
  424.   tanh(x)
  425.   exp(x)
  426.   log(x)
  427.   log10(x)
  428.   pow(x,y)
  429.   sqrt(x)
  430.   ceil(x)
  431.   floor(x)
  432.   fabs(x)
  433.   ldexp(x,n)
  434.   frexp(x, int *exp)
  435.   modf(x, double *ip)
  436.   fmod(x,y)
  437.  
  438.  
  439.  
  440. CHARACTER TESTS <ctype.h>
  441. _________________________________________________________________________
  442.  
  443. All functions in <ctype.h> take a character and return an 'int' which represents a true (non-zero) or false (zero) result.
  444.  
  445.   isalnum(int c)   alpha-numeric character
  446.   isalpha(int c)   upper or lower-case letter
  447.   iscntrl(int c)   control character
  448.   isdigit(int c)   decimal digit
  449.   isgraph(int c)   !space
  450.   islower(int c)   lower-case
  451.   isprint(int c)   printing character, including space
  452.   ispunct(int c)   !(space || letter || digit)
  453.   isspace(int c)   space, tab, newline
  454.   isupper(int c)   upper-case
  455.   isxdigit(int c)  hexadecimal digit
  456.  
  457.  
  458.  
  459. DATA AND TIME FUNCTIONS <time.h>
  460. _________________________________________________________________________
  461.  
  462. Many functions in <time.h> utilize a data structure which has the following format:
  463.  
  464.   struct tm
  465.   {
  466.     int tm_sec;
  467.     int tm_min;
  468.     int tm_hour;
  469.     int tm_mday;
  470.     int tm_mon;
  471.     int tm_year;
  472.     int tm_wday;
  473.     int tm_yday;
  474.     int tm_isdst;  // Daylight Savings Time flag
  475.   };
  476.  
  477. ASCTIME
  478. char *asctime(const struct tm *tp)
  479. Converst time into standard string; "Fri May 26 19:27:30 1995\n".
  480.  
  481. CLOCK
  482. clock_t clock(void)
  483. Returns processor time used by the program.
  484.  
  485. CTIME
  486. char *ctime(const time_t *tp)
  487. Converts calendar time to local time.
  488.  
  489. DIFFTIME
  490. double difftime(time_t time2, time_t time1)
  491. Returns difference in two times in seconds.
  492.  
  493. GMTIME
  494. struct tm *gmtime(const time_t *tp)
  495. Converts calendar time into Coordinated Universal Time (UTC).
  496.  
  497. LOCALTIME
  498. struct tm *localtime(const time_t *tp)
  499. Converts calendar time into local time.
  500.  
  501. MKTIME
  502. time_t mktime(struct tm *tp)
  503. Converts local time to calendar time.
  504.  
  505. STRFTIME
  506. size_t strftime(char *s,size_t smax,const char *fmt,const struct tm *tp)
  507. Formats date and time data from *tp into string 's'.  Available formats include:
  508.   %a  abbriviated weekday name
  509.   %A  full weekday
  510.   %b  abbreviated month
  511.   %B  full month
  512.   %c  date and time
  513.   %d  day of month (01-31)
  514.   %H  hour (24 hr)
  515.   %I  hour (12 hr)
  516.   %j  day of year
  517.   %m  month
  518.   %M  minute
  519.   %p  AM or PM
  520.   %S  second
  521.   %U  week number (Sunday 1st day of week)
  522.   %w  weekday (0-6)
  523.   %W  week number (Monday 1st day of week)
  524.   %x  date
  525.   %X  time
  526.   %y  year without century
  527.   %Y  century
  528.   %Z  time zone name
  529.   %%  %
  530.  
  531. TIME
  532. timt_t time(time_t *tp)
  533. Returns current calendar time.  If 'tp' is not NULL, return value is also assigned to 'tp'.
  534.  
  535.  
  536.  
  537. VARIABLE ARGUMENT LISTS <stdarg.h>
  538. _________________________________________________________________________
  539.  
  540. Use the functions in <stdarg.h> to retrieve arguments from a variable length function argument list.  An example of using variable argument lists can be found in Section 'Functions'.  Before using functions, you must declare a variable of type 'va_list' as follows:
  541.  
  542.   va_list ap;
  543.  
  544. You then use the 'va_start' macro to initialize.  Afterwords, each subsequent call to 'va_arg' returns the next argument.  Finally, call 'va_end'.
  545.  
  546. VA_START
  547. void va_start(va_list ap, lastarg)
  548. Provide the last argument in a variable length function list as 'lastarg' to initialize va_list variable.
  549.  
  550. VA_ARG
  551. type va_arg(va_list ap, type)
  552. Returns next argument in variable length function list.  You must supply the data type in 'type'.  va_arg returns type specified in 'type'.
  553.  
  554. VA_END
  555. void va_end(va_list ap)
  556. Execute after arguments have been processed, but prior to exiting function.
  557.  
  558.  
  559.  
  560. IMPLEMENTATION SPECIFICS <limits.h> and <float.h>
  561. _________________________________________________________________________
  562.  
  563. The following constants are defined in <limits.h>:
  564.  
  565.   CHAR_BIT
  566.   CHAR_MAX
  567.   CHAR_MIN
  568.   INT_MAX
  569.   INT_MIN
  570.   LONG_MAX
  571.   LONG_MIN
  572.   SCHAR_MAX
  573.   SCHAR_MIN
  574.   SHRT_MAX
  575.   SHRT_MIN
  576.   UCHAR_MAX
  577.   UINT_MAX
  578.   ULONG_MAX
  579.   USHRT_MAX
  580.  
  581. The following constants are defined in <float.h>:
  582.  
  583.   FLT_RADIX
  584.   FLT_ROUNDS
  585.   FLT_DIG
  586.   FLT_EPSILON
  587.   FLT_MANT_DIG
  588.   FLT_MAX
  589.   FLT_MAX_EXP
  590.   FLT_MIN
  591.   FLT_MIN_EXP
  592.   DBL_DIG
  593.   DBL_EPSILON
  594.   DBL_MANT_DIG
  595.   DBL_MAX
  596.   DBL_MAX_EXP
  597.   DBL_MIN
  598.   DBL_MIN_EXP
  599.  
  600.  
  601.  
  602. DIAGNOSTICS <assert.h>
  603. _________________________________________________________________________
  604.  
  605. Built-in diagnostic macro which is rarely used but included just to be complete.
  606.  
  607. ASSERT
  608. void assert(int expr)
  609. If 'expr' is zero, prints error message on stderr.  If NDEBUG is defined, assert macro is ignored.
  610.  
  611.  
  612.  
  613. NON-LOCAL JUMPS <setjmp.h>
  614. _________________________________________________________________________
  615.  
  616. Bad idea which is rarely used but included just to be complete.
  617.  
  618. SETJMP
  619. int setjmp(jmp_buf env)
  620. Saves state information for later use by 'longjmp'.
  621.  
  622. LONGJMP
  623. void longjmp( jmp_buf env, int val)
  624. Restores state saved by most recent call to setjmp.  Execution resumes as if the setjmp function had just executed and returned the non-zero value val.  Function containing setjmp must not have terminated.
  625.  
  626.  
  627.  
  628. SIGNALS <signal.h>
  629. _________________________________________________________________________
  630.  
  631. Precursor to C++ exception handling?  Rarely used but included just to be complete.
  632.  
  633. SIGNAL
  634. void (*signal(int sig, void (*handler)(int)))(int)
  635. Calls function pointed to by handler with argument of the type of signal.
  636.   SIG_DFL  default behavior: handler ignored
  637.   SIG_IGN  ignore signal: handler ignored
  638.   SIGABRT  abnormal termination
  639.   SIGFPE   arithmetic error
  640.   SIGILL   illegal instruction
  641.   SIGINT   interrupt
  642.   SIGSEGV  illegal storage access
  643.   SIGTERM  termination request
  644.  
  645. RAISE
  646. int raise( int sig )
  647. Sends the signal 'sig' to the program, returns non-zero is unsuccessful.